<!--
	$Id: readme_en.html 24 2007-05-01 07:52:43Z beave $
-->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xml:lang="en">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
		<title>Parser 3. Archive. Class for working with archives.</title>
		<style type="text/css">
			body {
				font-family: sans-serif;
				font-size: 70%;
			}
			h1 {
				color: green;
			}
			h2 {
				padding-top: 1em;
				border-bottom: 1px solid grey;
			}
			p.intro {
				padding-left: 50%;
				color: grey;
			}
			p.note {
				font-style: italic;
				color: brown;
			}
			pre {
				color: blue;
			}
		</style>
	</head>

	<body>
		<h1>Archive. Class for working with archives.</h1>
		<p class="intro">One day it became inconvenient to me to use ^file::cgi[...] for work with archives. I written a class helping me to work with them.</p>
		<p>The class supports archivers: tar (with compressors: gzip and bzip2), zip, rar. The class is used statically, i.e. there is no necessary for creation objects by constructors.</p>


		<!-- home directory / root path -->

		<h2>Home directory and root path.</h2>
		<p>By default the home directory to the class considers the directory in which placed or will be placed archive. The home directory is used for work with the archive's content at actions: creation and extraction.<br/> When full path to the file or directory on resource not specified, the class searches for the following file or directory relative to the home directory.</p>
		<p>&laquo;Root path&raquo; &#151; root of web-space ($request:document-root).</p>
<h4>Examples:</h4>
<p class="comment">Archive will be created in directory, which running script of Parser, and containing a file from this directory:</p>
<pre>
^Archive:create[db_dump.zip;db_dump-${dtNow.year}${dtNow.month}${dtNow.day}.sql]
</pre>
<p class="comment">The archive, located in the root path, will be extracted into the texts directory, placed on 2 step above relative to the home directory (in this case it is equal to the root path):</p>
<pre>^Archive:extract[/my_texts.rar;../../texts]</pre>


		<!-- static methods -->

		<h2>Static methods.</h2>
		<h3>init &#151; static class initialization</h3>
<pre>
^Archive:init[
	$.SCRIPT_PATH[path to script]
	$.DEBUG_OBJECT[object of debug-class]
]
</pre>
		<h4>Options:</h4>
		<p>
			<strong>$.SCRIPT_PATH[string]</strong> &#151; path to console script (<em>archive.sh</em> &#151; BASH / <em>archive.bat</em> &#151; MS-DOS)<br/>
			<strong>$.DEBUG_OBJECT[object]</strong> &#151; object of debug-class compatible with Debug (P3 XML Debugger)
		</p>
		<p class="note">Note: at repeated initialization of the class, in case if any options are not specified, it's gonna use values of the previous initialization if those are not present is't gonna use default values.</p>

		<h3>create &#151; archive creation</h3>
<pre>
^Archive:create[filename;content]
^Archive:create[filename;content;archiver]
^Archive:create[filename;content;archiver;compressor]
</pre>
		<p>
			<strong>filename[string]</strong> &#151; name of the file with path<br/>
			<strong>content[string|table]</strong> &#151; name of archived file(s) with path or table (object of <em>table</em> system class) containing one column <em>path</em>, containing archived files and directories with path (see also &laquo;Home directory and root path&raquo;)<br/>
			<strong>archiver[string]</strong> &#151; archiver name<br/>
			<strong>compressor[string]</strong> &#151; compressor name
		</p>
		<h3>extract &#151; archive extraction</h3>
<pre>
^Archive:extract[filename]
^Archive:extract[filename;path]
^Archive:extract[filename;path;archiver;compressor]
</pre>
		<p>Extracts archive into home directory or to the specified directory.</p>
		<p>
			<strong>filename[string]</strong> &#151; name of the file with path<br/>
			<strong>path[string]</strong> &#151; path to directory to extract content (see also &laquo;Home directory and root path&raquo;)<br/>
			<strong>archiver[string]</strong> &#151; archiver name<br/>
			<strong>compressor[string]</strong> &#151; compressor name
		</p>
		<h3>list &#151; getting archive content</h3>
<pre>
^Archive:list[filename]
^Archive:list[filename;archiver]
^Archive:list[filename;archiver;compressor]
</pre>
		<p>
			<strong>filename[string]</strong> &#151; name of the file with path<br/>
			<strong>archiver[string]</strong> &#151; archiver name<br/>
			<strong>compressor[string]</strong> &#151; compressor name
		</p>
		<p>Makes up table (object of <em>table</em> system class) containing one column <em>path</em>, containing archived files and directories.</p>
		<p class="note">Note: specified &lsquo;archiver&rsquo; or &lsquo;compressor&rsquo; parameteres will be used to the specified programs (supported by the class) because it is not dependent on file extension.</p>


		<!-- static fields -->

		<h2>Static fields.</h2>
		<h3>SCRIPT_PATH[string] &#151; retrieving console script file name</h3>
		<h3>ARCHIVER[string] &#151; retrieving archiver name</h3>
		<h3>COMPRESSOR[string] &#151; retrieving compressor name</h3>
		<p class="note">Note: retrieve &lsquo;archiver&rsquo; and &lsquo;compressor&rsquo; values will be possible only if you work with the archive (creation, extraction, etc.).</p>


		<!-- examples -->

		<h2>Examples of use.</h2>
		<h3>Loading and extracting archive from another web-resource.</h3>
		<p>Let's assume we need the method which specify link to archive on other resource, download the file, save it in the temporary directory and extract it to the directory necessary to you on the server.</p>
<pre>
@extractWebArchive[strURL;strTmpDir;strDirTo][sTmpDir;fArchive]
^if(!def $strURL){
	^throw[CLASS_NAME.spec;^$strURL;param not specified]
}

^if(def $strTmpDir){
	$sTmpDir[$strTmpDir]
}{
	$sTmpDir[/../data/tmp]
}

^if(^strURL.left(4) ne 'http'){
	^throw[CLASS_NAME.url.type;^$strURL;unknown url type]
}

$fArchive[^file::load[$strURL]]
^fArchive.save[binary;$sTmpDir]

^Archive:extract[$sTmpDir/$fArchive.name;$strDirTo]

$result[]
#end @extractWebArchive[]
</pre>
	</body>
</html>
